Function: toNode(stringMarkup, boolOnlyReturnNode, boolOnlyReturnArray)

Description: Converts a markup string into a DOM fragment, element node, or element node array.

Returns: domFragment, domElement, domElementArray, or $A object if chained.

Note: The toNode() function will return a document fragment by default when multiple elements are included at the same logical level. Otherwise, a standard DOM node will be returned. When boolOnlyReturnNode is set to true, a standard DOM node or document fragment will always be returned when passing an array of DOM nodes into the first parameter. When boolOnlyReturnArray is set to true, an array will always be returned instead.

If toNode() includes no arguments, then an empty document fragment element is returned.

Example:

// Create an empty document fragment.
var myFragment = $A.toNode();

// Create a document fragment with multiple elements at the same level.
var myElement = $A.toNode('<i>This is a test.</i><br /><i>So, try to look impressed.</i><br /><i>Hey, that rhymed!</i>');

// Return an array of all matching DOM nodes.
var myNodesArray = $A.toNode("h2", false, true);

// Convert an array of DOM nodes into a single document fragment element.
var myElement = $A.toNode(myNodesArray, true);

// Or the same using chaining

// Create a document fragment with multiple elements at the same level.
var myChain = $A('<i>This is a test.</i><br /><i>So, try to look impressed.</i><br /><i>Hey, that rhymed!</i>');

// Return an array of all matching DOM nodes.
var myChain = $A("h2").toNode(false, true);

// Convert an array of DOM nodes into a single document fragment element.
var myChain = $A(myNodesArray).toNode(true);

// To return the modified element within a chain, use the "return()" method.

var myElement = myChain.return();